GeneDock Offical Java SDK手册

前言

SDK下载

Offical Java SDK开发包最新版本0.0.8

简介

Offical Java SDK适用于JDK 7及以上版本；
本文主要介绍Offical Java SDK的安装、使用及注意事项；
并且假设您已经注册了GeneDock账号。

安装

环境准备

适用于JDK 7及以上版本

安装方式

方式一：在Eclipse项目中导入JAR包

以0.0.1为例，步骤如下：

下载Offical Java SDK开发包，版本号0.0.1：genedock-offical-java-20160629.zip；
解压该压缩包
lib目录下所有JAR包拷贝到您的项目中；
在Eclipse中选择您的工程，右击 -> Properties -> Java Build Path -> Add JARs；
选中您在第三步拷贝的所有JAR文件；

经过以上几步，您就可以在Eclipse项目中使用GeneDock Offical Java SDK。

初始化

GDClient是GeneDock服务的Java客户端，它为调用者提供一些列和GeneDock进行交互的接口，用于管理、操作工作流（Workflow）和任务（Task）等资源。使用Offical Java SDK发起请求，您需要初始化一个GDClient实例，并根据需要修改ClientConfiguration的默认配置项。

确定Endpoint

请先阅读API-Reference中关于服务入口说明的部分，了解目前GeneDock所有服务的入口地址。

目前GeneDock各个域（Region）的Endpoint如下：

Region	Endpoint
北京域	https://cn-beijing-api.genedock.com
深圳域	https://cn-shenzhen-api.genedock.com

获取密钥

要使用GeneDock的API服务，您需要一个有效的Access Key（包括AccessKeyId和AccessKeySecret）用来进行签名认证。如何获取密钥请参考命令行客户端使用手册中获取access_key_id和access_key_secret的说明。

获取了AccessKeyId和AccessKeySecret之后，您便可以按照以下的步骤进行初始化。

新建GDClient

新建一个GDClient的代码如下：

// endpoin以北京为例，其他region请根据实际情况填写
String endpoint = "https://cn-beijing-api.genedock.com";
// 请登录https://www.genedock.com查看accessKey
String accessKeyId = "<Please input your access key id>";
String accessKeySecret = "<Please input your access key secret>";

// 创建GDClient实例
GDClient client = new GDClient(endpoint, accessKeyId, accessKeySecret);

提示：

您的工程中可以有多个GDClient，也可以只有一个GDClient；

GDClient可以并发使用；

为了安全，GeneDock公有域中目前只支持https协议访问；

GDClient.shutdown 执行以后实例不能再被使用。

配置GDClient

如果您需要修改GDClient的一些默认配置，请在构造GDClient的时候传入ClientConfiguration实例。ClientConfiguration是GDClient的配置类，可以配置代理、连接超时、最大连接数等参数。通过ClientConfiguration可以设置的参数见下表：

参数	描述	设置方法
MaxConnections	允许打开的最大HTTP连接数。默认为1024	ClientConfiguration.setMaxConnections
SocketTimeout	Socket层传输数据的超时时间(单位:毫秒)。默认为50000毫秒	ClientConfiguration.setSocketTimeout
ConnectionTimeout	建立连接的超时时间(单位:毫秒)。默认为50000毫秒	ClientConfiguration.setConnectionTimeout
ConnectionRequestTimeout	从连接池中获取连接的超时时间(单位:毫秒)。默认不超时	ClientConfiguration.setConnectionRequestTimeout
IdleConnectionTime	关闭空闲该时长的连接(单位:毫秒)。默认为60000毫秒	ClientConfiguration.setIdleConnectionTime
MaxErrorRetry	请求失败后最大的重试次数。默认3次	ClientConfiguration.setMaxErrorRetry
Protocol	连接GeneDock服务所采用的协议（http/https），默认为https	ClientConfiguration.setProtocol
UserAgent	用户代理,指HTTP的User-Agent头。默认为“genedock-offical-java-sdk”	ClientConfiguration.setUserAgent
ProxyHost	代理服务器主机地址	ClientConfiguration.setProxyHost
ProxyPort	代理服务器端口	ClientConfiguration.setProxyPort
ProxyUsername	代理服务器验证的用户名	ClientConfiguration.setProxyUsername
ProxyPassword	代理服务器验证的密码	ClientConfiguration.setProxyPassword
ProxyDomain	访问NTLM验证的代理服务器的Windows域名	ClientConfiguration.setProxyDomain
ProxyWorkstation	NTLM代理服务器的Windows工作站名称	ClientConfiguration.setProxyWorkstation

使用ClientConfiguration设置GDClient参数代码如下：

// endpoin以北京为例，其他region请根据实际情况填写
String endpoint = "https://cn-beijing-api.genedock.com";
// 请登录https://www.genedock.com查看accessKey
String accessKeyId = "<Please input your access key id>";
String accessKeySecret = "<Please input your access key secret>";

// 创建ClientConfiguration实例
ClientConfiguration conf = new ClientConfiguration();

// 设置GDClient使用的最大连接数,默认1024
conf.setMaxConnections(200);

// 设置请求超时时间,默认50000毫秒
conf.setSocketTimeout(10000);

// 设置失败请求重试次数,默认3次
conf.setMaxErrorRetry(5);

// 创建GDClient实例
GDClient client = new GDClient(endpoint, accessKeyId, accessKeySecret, conf);

// 使用访问GeneDock服务

// 关闭GDClient
client.shutdown();

快速入门

请确认您已经熟悉GeneDock的主要概念，如工作流、任务等。本节您将看到如何快速使用Offical Java SDK，完成对工作流和任务的常见操作。

初始化GDClient

向GeneDock发送任一HTTP请求之前，必须先创建一个GDClient实例：

// endpoin以北京为例，其他region请根据实际情况填写
String endpoint = "https://cn-beijing-api.genedock.com";
// 请登录https://www.genedock.com查看accessKey
String accessKeyId = "<Please input your access key id>";
String accessKeySecret = "<Please input your access key secret>";

// 创建GDClient实例
GDClient client = new GDClient(endpoint, accessKeyId, accessKeySecret);

// 使用访问GeneDock服务

// 关闭GDClient
client.shutdown();

提示：

更多GDClient初始化的内容请参考初始化

Tool操作

CreateTool

以下的代码展示如何在默认project下新建一个Tool：

int toolVersion = 1;
client.createTool("<accountName>", "default", "<toolName>", <toolVersion>, "<ToolDescription>");

提示：

Tool的命名规范，请参见API-Reference CreateTool的说明。

新建的tool的status是unchecked，不可以被列出或使用。只有正确执行了PutTool操作以后，状态变成checked后，工作才可以被列出和使用。

默认版本号为1

PutTool

此接口用来创建和更新Tool的定义。以下的代码展示如何给新建的Tool添加定义：

client.putTool("<accountName>", "default", "<toolName>", <toolVersion>, "<toolConfigs>", "<toolDescription>");

提示：

工具定义配置必须是合法json字符串,说明请参见PutTool Configs 说明。

GetTool

以下的代码展示如何获取一个指定tool的信息：

ToolList tools = client.getTool("<accountName>", "default", "<toolName>", <toolVersion>);
for (Tool t : tools.getToolList()) {
    System.out.println(t);
}

GetToolParameterTemplate

以下的代码展示如何获取一个指定tool的参数模板：

String parameterTemplate = client.getToolParameterTemplate("<accountName>", "default", "<toolName>", <toolVersion>);
System.out.println(parameterTemplate);

GetToolDetails

以下的代码展示如何获取一个指定tool的输入输出和参数等详情：

String details = client.getToolDetails("<accountName>", "default", "<toolName>", <toolVersion>);
System.out.println(details);

ListTool

以下的代码展示如何列举某账号下的tool：

ToolList tools = client.listTool("<accountName>", "default");
for (Tool t : tools.getToolList()) {
    System.out.println(t);
}

提示：

只能列出状态为checked的工具

DeleteTool

以下的代码展示如何删除一个tool：

client.deleteTool("<accountName>", "default", "<toolName>", <toolVersion>);

提示：

只能删除状态为checked或者unchecked的工具。

Workflow操作

CreateWorkflow

以下的代码展示如何默认在project下新建一个workflow：

// 目前只支持默认的project
int workflowVersion = 1;
client.createWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>);

提示：

Workflow的命名规范，请参见API-Reference CreateWorkflow的说明。

新建的workflow的status是unchecked，不可以被运行。只有正确执行了PutWorkflow操作以后，状态变成checked后，工作流才可以被运行。

PutWorkflow

此接口用来创建和更新workflow的定义。以下的代码展示如何给新建的workflow添加定义：

// 添加工作流定义
client.putWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>, "<workflowDescription>", <workflowConfigs>);

提示：

工作流定义配置的说明请参见PutWorkflow Configs 说明。

GetWorkflow

此接口用来获取workflow的定义。以下代码展示如何获取指定workflow的定义：

// 获取工作流定义
List<Workflow> workflowList = client.getWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>);
for(Workflow w : workflowList) {
    System.out.println(w);
}

GetExecutableWorkflow

此接口用来获取workflow的参数模版。以下代码展示如何获取指定workflow的参数模版：

// 获取工作流参数模版
Workflow workflow = client.getExecutableWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>);
System.out.println(workflow);

DeleteWorkflow

以下代码展示如何删除指定workflow：

client.deleteWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>);

ListWorkflow

有时候可能需要查看一个账号下的所有工作流(不一定有运行权限)。以下代码展示如何列举某账号下的workflow：

WorkflowsList workflowsList = client.listWorkflow("<accountName>", "default");
for(List<Workflow> workflows : workflowsList.getWorkflowsList()) {
    for (Workflow workflow : workflows) {
        System.out.println(workflow);
    }
}

ListExecutableWorkflow

此接口可以列出所有可以运行的工作流。以下代码展示如何列举某账号下可运行的workflow：

WorkflowsList workflowsList = client.listExecutableWorkflow("<accountName>", "default");
for(List<Workflow> workflows : workflowsList.getWorkflowsList()) {
    for (Workflow workflow : workflows) {
        System.out.println(workflow);
    }
}

ActivateWorkflow

以下的代码展示如何从workflow生成一个task：

Task task = client.activateWorkflow("<accountName>", "default", "<workflowName>", <workflowVersion>, "<taskName>", <taskParameters>);
System.out.println(task);

提示：

Task参数的说明请参见ActivateWorkflow Parameters 说明。

Task名字的规范请参见API-Reference ActivateWorkflow。

Task操作

GetTask

投递了一个新的task后，有时候需要看一下task的状态等信息。以下的代码展示如何获取一个task的meta信息：

Task task = client.getTask("<accountName>", "default", "<taskId>");
System.out.println(task);

ListTask

以下的代码展示如何列举某账号下的task：

TaskList tasks = client.listTask("<accountName>", "default");
for (Task t : tasks.getTaskList()) {
    System.out.println(t);
}

StopTask

以下的代码展示如何停止一个task：

client.stopTask("<accountName>", "default", "<taskId>");

DeleteTask

以下的代码展示如何删除一个task：

client.deleteTask("<accountName>", "default", "<taskId>");

提示：

只能删除状态为success、failed或者compiled的任务。

ListJob

以下的代码展示如何列举一个task下所有job的信息：

JobList jobs = client.listJob("<accountName>", "default", "<taskId>");
for (Job job : jobs.getJobList()) {
    System.out.println(job);
}

GetJob

以下的代码展示如何获取一个Job的meta信息：

Job job = client.getJob("<accountName>", "default", "<taskId>", "<jobId>");
System.out.println(job);

异常处理

调用GDClient类的相关接口时，如果抛出异常，则表明操作失败，否则操作成功。抛出异常时，方法返回的数据无效。GeneDock Offical Java SDK包含两类异常，一类是服务器端异常GDException，另一类是客户端异常ClientException，它们均继承自RuntimeException。

异常处理示例

try {
    // 使用GDClient 做一些操作，例如创建工作流等

    client.createWorkflow("accountName", "default", "workflowName", 1);           
} catch (GDException oe) {
    System.out.println("Caught an GDException, which means your request made it to GeneDock, "
            + "but was rejected with an error response for some reason.");
    System.out.println("Error Message: " + oe.getErrorMessage());
    System.out.println("Error Code:       " + oe.getErrorCode());
    System.out.println("Request ID:      " + oe.getRequestId());
    System.out.println("Host ID:           " + oe.getHostId());
} catch (ClientException ce) {
    System.out.println("Caught an ClientException, which means the client encountered "
            + "a serious internal problem while trying to communicate with GeneDock, "
            + "such as not being able to access the network.");
    System.out.println("Error Message: " + ce.getMessage());
} finally {
    client.shutdown();
}

ClientException

ClientException表示客户端尝试向GeneDock发送请求以及数据传输时遇到的异常。例如，当发送请求时网络连接不可用时，则会抛出 ClientException。

GDException

GDException指服务器端错误，它来自于对服务器错误信息的解析，包含GeneDock会返回给用户相应的错误码和错误信息，便于用户定位问题，并做出适当的处理。

GDException通常包含以下错误信息：

Code: GeneDock返回给用户的错误码。
Message: GeneDock提供的详细错误信息。
RequestId: 用于唯一标识该请求的UUID；当您无法解决问题时，可以凭这个RequestId来请求GeneDock开发工程师的帮助。
HostId: 用于标识访问的GeneDock集群，与用户请求时使用的Host一致。

常见错误码请参见API-Reference。